home *** CD-ROM | disk | FTP | other *** search
/ User's Choice Windows CD / User's Choice Windows CD (CMS Software)(1993).iso / windows5 / vlib101.zip / VIEWLIB.MAN < prev    next >
Text File  |  1992-04-14  |  21KB  |  751 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                                        ViewLib
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                                    Reference Manual
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.                          Copyright 1992, DB/Soft Publishing.
  31.                                  All rights reserved.
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.                                 Printed in the U.S.A.
  41.  
  42.                              Version 1.00, first printing
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.           Copyright________________________________________________________
  51.  
  52.           This software is protected under  United States Copyright Law and
  53.           International Treaty provisions.  DB/Soft Publishing reserves all
  54.           rights to ViewLib except for the following:
  55.  
  56.           A limited license is hereby granted allowing you use and evaluate
  57.           ViewLib for up  to 30 days.  You may also distribute unregistered
  58.           copies of  ViewLib  in its  entirety  to any  parties  interested
  59.           provided no  modification of  the  files in  the ViewLib  archive
  60.           occurs.    The  maximum  transaction  related  to  selling  media
  61.           containing unregistered copies of ViewLib  (eg Shareware vendors)
  62.           may not exceed $10.00.   Conversion to a more  convenient archive
  63.           format  is allowed.    All other  uses  of ViewLib  violate  this
  64.           license and are hereby expressly disallowed.
  65.  
  66.                         Copyright 1992, by DB/Soft Publishing,
  67.                                  All Rights Reserved.
  68.  
  69.                     3200 Truxel Rd #199, Sacramento, CA 95833 USA
  70.  
  71.                               Telephone: (916) 927-6951
  72.  
  73.                                  BBS: (916) 927-2349
  74.  
  75.           Limited Warranty_________________________________________________
  76.  
  77.           DB/Soft Publishing  grants no warranties, express  or implied, by
  78.           statute  or otherwise,  regarding this  software and  its related
  79.           materials, their fitness for any purpose, their quality, or their
  80.           merchantability.  In  no way shall  DB/Soft Publishing be  liable
  81.           for  any  special, consequential,  other  damages  for breach  of
  82.           warranty.
  83.  
  84.           This Statement  shall be  construed, interpreted and  governed by
  85.           the laws of the State of California.
  86.  
  87.           This  warranty will be replaced by a limited 90-day warranty that
  88.           covers the diskette, software and documentation upon registration
  89.           of ViewLib.
  90.  
  91.  
  92.           Registering ViewLib______________________________________________
  93.  
  94.           ViewLib  is an example  of software marketed  under the Shareware
  95.           concept.  The premise is simple:  you may evaluate  ViewLib for a
  96.           reasonable period  of time  (30 days  maximum)  during which  you
  97.           decide if  it is  a library  worth owning  and using  for viewing
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.           files  from within your applications.   If so,  you must register
  106.           ViewLib, using order.doc for  ordering information.  If, after  a
  107.           reasonable evaluation period, you decide not to register ViewLib,
  108.           you then must discontinue its use.
  109.  
  110.           This  provides me  with a way  to market  software with  very low
  111.           advertising  overhead, which  results in  a price  savings passed
  112.           directly on to you.  And, it provides you with a chance to 'play'
  113.           with my product and decide if it meets your needs. 
  114.  
  115.           As an incentive to speed the registration process, only the small
  116.           memory  model  of ViewLib  is  distributed  as shareware.    Upon
  117.           registration, you  will receive all the  available memory models:
  118.           small, medium,  compact  and  large,  for both  Borland  C++  and
  119.           Microsoft C.
  120.  
  121.  
  122.           Getting Help_____________________________________________________
  123.  
  124.           There are several ways of contacting the author, Jeff Dunlop, for
  125.           technical assistance if you get stuck.  From cheapest and slowest
  126.           to most expensive and fastest:
  127.  
  128.                - Fidonet's SHAREWRE or C_ECHO echoes
  129.  
  130.                - ILink's Shareware conference
  131.  
  132.                - Fidonet netmail at 1:203/16
  133.  
  134.                - The DB/Soft Online at (916) 927-2349
  135.  
  136.           The best method of  contacting the author depends on the  type of
  137.           assistance you need.   If it's a rather complicated  problem, you
  138.           will probably be far  better served if  you prepare a message  in
  139.           advance  and upload  it  with a  source  example to  the  DB/Soft
  140.           Online.  We can then test it and offer suggestions.  If it's just
  141.           a question or suggestion about ViewLib capabilities, the ILink or
  142.           Fidonet conferences  will work best.   Fidonet netmail privileges
  143.           can be difficult to  get, but offer excellent timeliness  at very
  144.           low connect time.  Check your local Fidonet BBS if interested.
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.                                   Table of Contents
  153.  
  154.  
  155.                Chapter 1 Introduction .................................. 2
  156.                     Features ........................................... 2
  157.                     Requirements ....................................... 2
  158.                     Getting Started .................................... 2
  159.  
  160.                Chapter 2 Function Reference ............................ 4
  161.                     vlLister ........................................... 4
  162.                     vlGetVidMode ....................................... 6
  163.                     vlGetVidBase ....................................... 7
  164.                     vlGetCols .......................................... 7
  165.                     vlGetRows .......................................... 8
  166.                     vlIsDV ............................................. 9
  167.                     vlIsEgaVga ......................................... 9
  168.                     vlIsShift .......................................... 10
  169.                     vlIsRShift ......................................... 10
  170.                     vlIsLShift ......................................... 10
  171.                     vlIsMono ........................................... 10
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.                                           1
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.           Chapter 1 
  208.  
  209.           Introduction_____________________________________________________
  210.  
  211.  
  212.           Features_________________________________________________________
  213.  
  214.           ViewLib provides an excellent means  to providing report and file
  215.           viewing from  within  your C  applications.   Some  of  ViewLib's
  216.           features include:
  217.  
  218.               -     View any size file
  219.  
  220.               -     Resize and move the view window at will
  221.  
  222.               -     Completely define the color of the text and border.  
  223.  
  224.               -     Completely  define  the  characters  that  compose  the
  225.                     border.
  226.  
  227.               -     Define the initial size of the View window.
  228.  
  229.               -     ViewLib can  operate with as  little as  30k free  ram,
  230.                     which  is  released  back   to  your  application  when
  231.                     finished.
  232.  
  233.               -     Desqview, EGA  and VGA are all  detected and respected.
  234.                     In DesqView, the shadow buffer is used to avoid  bleed-
  235.                     through to other tasks. 
  236.  
  237.           Requirements_____________________________________________________
  238.  
  239.           You  must own either a Microsoft  or Borland C compiler.  ViewLib
  240.           should  be compatible  with  most if  not  all of  the  compilers
  241.           produced by  these two  companies, and  with any  other companies
  242.           that  produces compatible compilers  (Watcom comes to  mind).  If
  243.           you require ViewLib's functionality with an unsupported compiler,
  244.           the  only solution  is to  purchase the  source code  (please see
  245.           order.doc for details).
  246.  
  247.           Getting Started__________________________________________________
  248.  
  249.           ViewLib  can be linked into  any application just  like any other
  250.           library.    Therefore, you  should  copy  vl*.lib into  the  same
  251.           directory  that you  keep your  other  .lib files  in.   The file
  252.  
  253.  
  254.                                           2
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.           vlibbcs.lib  is for  Borland  compilers, and  vlibmscs.lib is for
  263.           Microsoft compilers.
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.                                           3
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.           Chapter 2
  318.  
  319.           Function
  320.           Reference________________________________________________________
  321.  
  322.  
  323.           vlLister_________________________________________________________
  324.  
  325.              Usage: int vlLister(char  *FileSpec, int  x1, int y1,  int x2,
  326.                     int  y2,  unsigned   char  Foreground,  unsigned   char
  327.                     Background, unsigned BufSize, BORDER *BorderInfo);
  328.  
  329.              Prototype in:  vlib.h
  330.  
  331.              Description:   vlLister  displays  in  the coordinates  x1, y1,
  332.                             x2,  y2 the  filename  passed.   The coordinates
  333.                             are 0-based.   The minimum  allowed buffer  size
  334.                             is eight kilobytes (8092  bytes).  The suggested
  335.                             optimum buffer size is  also 8k.   The only time
  336.                             that  it might  be  beneficial to  work  with  a
  337.                             larger buffer is  in the case of reading a  file
  338.                             on  a  floppy  drive.    The  valid  colors  for
  339.                             Background (defined in vlib.h) are as follows:
  340.  
  341.                             BLACK, BLUE, GREEN, CYAN,  RED, MAGENTA,  BROWN,
  342.                             LIGHTGREY
  343.  
  344.  
  345.                             The valid colors  for Foreground are any of  the
  346.                             colors valid for Background, plus:
  347.  
  348.                             DARKGREY,   LIGHTBLUE,  LIGHTGREEN,   LIGHTCYAN,
  349.                             LIGHTRED, LIGHTMAGENTA, YELLOW, WHITE
  350.  
  351.  
  352.                             The user-accessable fields of BorderInfo are:
  353.  
  354.                             bd_enable:  Set to  TRUE if  a border is  to be
  355.                                         displayed.   If  set to  FALSE, all
  356.                                         other values are ignored.
  357.  
  358.                             b_string:   A string  describing the characters
  359.                                         that  are  used   to  construct   a
  360.                                         border.  Any character value in the
  361.                                         extended   IBM  character   set  is
  362.  
  363.  
  364.                                           4
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.                                         valid.  The string  "┌─┐│└─┘" would
  373.                                         make a box similar to:
  374.                                               ┌──────┐
  375.                                               │      │
  376.                                               └──────┘
  377.  
  378.                             Foreground: The    colors   valid    for   text
  379.                                         foreground are valid here as well.
  380.  
  381.                             Background: The    colors   valid    for   text
  382.                                         background are valid here as well.
  383.  
  384.  
  385.           Return value:  Upon  successful  completion, vlLister  returns 0.
  386.                          The following error codes are defined in vlib.h:
  387.  
  388.                        VLIB_ARGERR
  389.                        VLIB_DOSERR
  390.                        VLIB_ALLOCERR
  391.  
  392.              Example:
  393.  
  394.              #include "vlib.h"
  395.  
  396.              void main(void)
  397.              {
  398.  
  399.                BORDER BorderInfo = {{TRUE}, {"┌─┐│└─┘"}, {YELLOW}, {BLUE}};
  400.  
  401.                vlLister("file.txt",  1, 1,  78,  23, YELLOW,  BLUE, 0x2000,
  402.                &bd_info);
  403.              }
  404.  
  405.           The behavior  of vlLister depends on whether BorderInfo.bd_enable
  406.           is TRUE or FALSE.   If the border is disabled, then it is assumed
  407.           that the calling  function has  prepared a custom  border and  so
  408.           border resizing/window moving is disabled as well.  If the border
  409.           is enabled, then the base of the border  has the following string
  410.           displayed:
  411.  
  412.                   PgUp PgDn Home End Esc
  413.  
  414.           These are a subset of the allowed  keystrokes.  The complete list
  415.           of legal keystrokes is:
  416.  
  417.           Home:   Display from the top of the file
  418.  
  419.                                           5
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.           End:    Display the end of the file
  428.  
  429.           PgUp:   Display  the  previous  page  (varies  according  to   the
  430.                   current window size.
  431.  
  432.           PgDn:   Display the  next page  (varies according  to the  current
  433.                   window size
  434.  
  435.           Down:   Display the next line.
  436.  
  437.           Up:     Display the previous line.
  438.  
  439.           Right:  Shift the display left 10 columns.
  440.  
  441.           Left:   Shift the display right 10 columns.
  442.  
  443.           *Ctl-Right, 
  444.           RShift-Right:  Lengthen the window to the right one column.
  445.  
  446.           *Ctl-Left, 
  447.           RShift-Left:   Shorten the window to the left one column.
  448.  
  449.           *Ctl-Dn, 
  450.           RShift-Dn:     Lengthen the window down one row.
  451.  
  452.           *Ctl-Up, 
  453.           RShift-Up:     Shorten the window up one row.
  454.  
  455.           LShift-Right:  Move the window right one column.
  456.  
  457.           LShift-Up:     Move the window up one row.
  458.  
  459.           LShift-Left:   Move the window left one column.
  460.  
  461.           LShift-Dn:     Move the window down one row.
  462.  
  463.           *Requires  an enhanced  (101-key, AT or  greater) keyboard.   The
  464.           RShift- commands work on all IBM PC-compatible keyboards.
  465.  
  466.  
  467.           vlGetVidMode_____________________________________________________
  468.  
  469.              Usage: unsigned char vlGetVidMode(void);
  470.  
  471.              Prototype in:  vlib.h
  472.  
  473.  
  474.                                           6
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.              Description:   vlGetVidMode returns the current  video mode  as
  483.                             reported by Bios.
  484.  
  485.              Return Value:  Refer  to a  MS-Dos  technical  reference manual
  486.                             for  the  possible return  values of  Bios video
  487.                             modes and their meanings.
  488.  
  489.              Example:
  490.  
  491.              #include <stdio.h>
  492.              #include "vlib.h"
  493.  
  494.              void main(void)
  495.              {
  496.                printf("Current video mode is %d\n", vlGetVidMode());
  497.              }
  498.  
  499.  
  500.           vlGetVidBase_____________________________________________________
  501.  
  502.              Usage: unsigned vlGetVidbase(void);
  503.  
  504.              Prototype in:  vlib.h
  505.  
  506.              Description:   vlGetVidBase returns the segment  of the current
  507.                             video display buffer.
  508.  
  509.              Return Value:  Usually, b000  will be  returned for  monochrome
  510.                             display,  and b800  for  all others.    However,
  511.                             DesqView  shadow  buffers may  contain different
  512.                             addresses on some platforms.
  513.  
  514.              Example:
  515.  
  516.              #include <stdio.h>
  517.              #include "vlib.h"
  518.  
  519.              void main(void)
  520.              {
  521.                printf("The  current  video  ram  base  address  is  %ud\n",
  522.                vlGetVidBase());
  523.              }
  524.  
  525.  
  526.           vlGetCols________________________________________________________
  527.  
  528.  
  529.                                           7
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.              Usage: int vlGetCols(void);
  538.  
  539.              Prototype in:  vlib.h
  540.  
  541.              Description:   vlGetCols   determines  the  number  of  columns
  542.                             currently being displayed.
  543.  
  544.              Return Value:  Most systems will  return 80 columns.   However,
  545.                             DesqView windows  defined at  unusual sizes will
  546.                             be detected,  as  will  132-column  (and  other)
  547.                             displays.
  548.  
  549.              Example:
  550.  
  551.              #include <stdio.h>
  552.              #include "vlib.h"
  553.  
  554.              void main(void)
  555.              {
  556.                printf("The monitor  is currently displaying  %d columns\n",
  557.                vlGetCols());
  558.              }
  559.  
  560.  
  561.           vlGetRows________________________________________________________
  562.  
  563.              Usage: int vlGetRows(void);
  564.  
  565.              Prototype in:  vlib.h
  566.  
  567.              Description:   vlGetRows   determines   the  number   of   rows
  568.                             currently being displayed.
  569.  
  570.              Return Value:  Most  systems  will return  25  rows.   However,
  571.                             DesqView windows  defined at unusual sizes  will
  572.                             be detected,  as will  43-column, 50-column (and
  573.                             other) displays.
  574.  
  575.              Example:
  576.  
  577.              #include <stdio.h>
  578.              #include "vlib.h"
  579.  
  580.              void main(void)
  581.              {
  582.  
  583.  
  584.                                           8
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                printf("The  monitor is  currently  displaying  %d  rows\n",
  593.                vlGetRows());
  594.              }
  595.  
  596.  
  597.           vlIsDV___________________________________________________________
  598.  
  599.              Usage: int vlIsDV(void);
  600.  
  601.              Prototype in:  vlib.h
  602.  
  603.              Description:   vlIsDV  determines whether DesqView is installed
  604.                             and active.
  605.  
  606.              Return Value:  If  DesqView  is  active,  vlIsDV returns  TRUE;
  607.                             otherwise, FALSE is returned.
  608.  
  609.              Example:
  610.  
  611.              #include <stdio.h>
  612.              #include "vlib.h"
  613.  
  614.              void main(void)
  615.              {
  616.                printf("DesqView %s active\n", vlIsDV() ? "is" : "is not");
  617.              }
  618.  
  619.  
  620.           vlIsEgaVga_______________________________________________________
  621.  
  622.              Usage: int vlIsEgaVga(void);
  623.  
  624.              Prototype in:  vlib.h
  625.  
  626.              Description:   vlIsEgaVga  determines whether an enhanced color
  627.                             adapter is installed.
  628.  
  629.              Return Value:  If  an   EGA  or  VGA   adapter  is   installed,
  630.                             vlIsEgaVga  returns  TRUE; otherwise,  FALSE  is
  631.                             returned.
  632.  
  633.              Example:
  634.  
  635.              #include <stdio.h>
  636.              #include "vlib.h"
  637.  
  638.  
  639.                                           9
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.              void main(void)
  648.              {
  649.                printf("An EGA or VGA monitor %s installed.\n", vlIsEgaVga()
  650.                ? "is" : "is not");
  651.              }
  652.  
  653.  
  654.           vlIsShift
  655.           vlIsRShift
  656.           vlIsLShift_______________________________________________________
  657.  
  658.              Usage: int vlIsLshift(void);
  659.                     int vlIsRshift(void);
  660.                     int vlIsShift(void);
  661.  
  662.              Prototype in:  vlib.h
  663.  
  664.              Description:   vlIsShift,  vlIsLShift and vlIsRShift return the
  665.                             status  of  the shift  keys  as appropriate  for
  666.                             each function.
  667.  
  668.              Return Value:  If the appropriate  shift key is being  pressed,
  669.                             the function returns  TRUE;  otherwise, FALSE is
  670.                             returned.
  671.  
  672.              Example:
  673.  
  674.              #include <stdio.h>
  675.              #include "vlib.h"
  676.  
  677.              void main(void)
  678.              {
  679.                printf("A shift key %s being pressed.\n", vlIsShift() ? "is"
  680.                : "is not"); 
  681.              }
  682.  
  683.  
  684.           vlIsMono_________________________________________________________
  685.  
  686.              Usage: int vlIsMono(void);
  687.  
  688.              Prototype in:  vlib.h
  689.  
  690.              Description:   vlIsMono determines  if the  current video  mode
  691.                             is monochrome.
  692.  
  693.  
  694.                                           10
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.              Return Value:  If  the  current  video   mode  is   monochrome,
  703.                             vlIsMono   returns  TRUE;  otherwise,  FALSE  is
  704.                             returned.
  705.  
  706.              Example:
  707.  
  708.              #include <stdio.h>
  709.              #include "vlib.h"
  710.  
  711.              void main(void)
  712.              {
  713.                printf("The monitor %s monochrome video mode.\n", vlIsMono()
  714.                ? "is" : "is not");
  715.              }
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.                                           11
  750.  
  751.